Skip to content

feat: multi-tenant — let a learner choose which Open edX platform to sign in to - #496

Open
IvanStepanok wants to merge 5 commits into
openedx:developfrom
raccoongang:feat/lms-multitenant
Open

feat: multi-tenant — let a learner choose which Open edX platform to sign in to#496
IvanStepanok wants to merge 5 commits into
openedx:developfrom
raccoongang:feat/lms-multitenant

Conversation

@IvanStepanok

Copy link
Copy Markdown
Contributor

What this adds

A build of this app normally talks to exactly one Open edX site, named in
config.yaml. With LMS_DIRECTORY enabled it instead shows a list of platforms,
lets the learner pick one, re-themes to it — logo, accent colour, sign-in artwork
— and signs in against that one. Logging out returns to the list, so a device can
move between platforms without a new build.

Off by default. With ENABLED: false none of this runs and the app behaves
exactly as it does today. Every shipped config in this PR has it disabled with no
source set.

Where the list comes from

One JSON document, given either way — never both:

LMS_DIRECTORY:
  ENABLED: true
  DIRECTORY_URL: "https://example.com/lms_directory.json"   # fetched once
  DIRECTORY_FILE: ""                                        # or: "lms_directory.json" in app/src/main/assets

A bundled file wins over an address: a build that ships its own copy has
deliberately opted out of the network, and quietly preferring a remote list would
undo that. Image fields inside the document are either web addresses or names of
files shipped with the app, so a build can be fully offline — list and artwork
both — and still be branded.

Because the whole list arrives at once, every platform's sign-in background is
known before anything is tapped. That is what makes it possible to warm the
artwork while the learner is still choosing, instead of watching the branded
screen assemble itself afterwards.

Format, both delivery modes and a worked example: Documentation/LMSDirectory.md.

Scope

Multi-tenancy only: read a list, choose, sign in, log out, choose again. No
search, no QR sign-in, no reporting a platform, and nothing that talks to a
catalog service — the app knows about a document and nothing else. Those belong
to a universal-app phase and will come as their own PRs.

Testing

Unit tests across core, auth, app and profile: 281 tests, 0 failures,
with detektAll clean over the whole project. They cover which source a config
resolves to, reading a document from assets and from a URL, image references
resolving to an address or to file:///android_asset/…, the picker's states, and
what choosing a platform writes — the host, OAuth client and branding everything
downstream reads.

One of them pins the smallest document a person could reasonably write by hand,
because the same file has to work on iOS too.

Notes for reviewers

  • BaseUrlOverrideInterceptor is what makes the chosen platform the one the app
    talks to, so a single-tenant build is unaffected: with nothing selected it does
    not rewrite anything.
  • Logging out clears the selected platform along with the session, so the next
    learner is not silently handed the previous one's host and branding.

A build normally talks to exactly one site, named in config.yaml. With
LMS_DIRECTORY enabled it instead shows the platforms listed in a JSON document,
re-themes to whichever the learner picks — logo, accent colour, sign-in artwork —
and signs in against that one. Logging out returns to the list, so a device can
move between platforms without a new build.

Off by default: with ENABLED false none of this runs.

The document is the whole contract. It comes from a URL or from the app's assets,
and nothing downstream can tell which — so a build can ship its list and its
images and never ask the network for either. Because the whole list arrives at
once, every platform's sign-in background is known before anything is tapped,
which is what lets that artwork be warmed while the learner is still choosing
rather than assembling itself afterwards.

Image references carry either an http(s) address or the name of a file in
assets, which Coil reads as file:///android_asset/… natively. One field, one
rule: the alternative was a parallel set of asset fields and a precedence rule
to go with them, which puts the rule in documentation instead of in the value.

Documentation/LMSDirectory.md has the format, both delivery modes and a worked
example.
@openedx-webhooks openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Aug 20, 2026
@openedx-webhooks

openedx-webhooks commented Aug 20, 2026

Copy link
Copy Markdown

Thanks for the pull request, @IvanStepanok!

This repository is currently maintained by @openedx/openedx-mobile-maintainers.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

  • If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
    • This process (including the steps you'll need to take) is documented here.
  • If it doesn't, simply proceed with the next step.
🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

  • Dependencies

    This PR must be merged before / after / at the same time as ...

  • Blockers

    This PR is waiting for OEP-1234 to be accepted.

  • Timeline information

    This PR must be merged by XX date because ...

  • Partner information

    This is for a course on edx.org.

  • Supporting documentation
  • Relevant Open edX discussion forum threads
🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details
Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

  • The size and impact of the changes that it introduces
  • The need for product review
  • Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

The app crashed on launch with the directory configured: Koin had no definition
for SiteSelectionViewModel, so the very first screen threw. Unit tests and the
build were both green — it took running the app to see it.

The rest is design parity, from putting the two screens side by side:

- the title sat under the status bar, so the screen needed statusBarsPadding;
- secondary text used appColors.textSecondary, which on Android is a light grey
  (#B3B3B3) while the token of that name on iOS is the slate #3D4964. The colour
  iOS actually draws is textPrimaryVariant here, so the subtitle, the host, the
  provider line and the chevron all use that;
- the chevron was the accent colour, where iOS draws it in the same secondary
  ink as the text;
- rows padded 12/10/10/4 against iOS's even 16, and the platform name used a
  title style where iOS uses bodyLarge.
@IvanStepanok

Copy link
Copy Markdown
Contributor Author

To test this MR you can create a JSON file by using my service: https://providers.openedx-lms.stepanok.com
Or use this JSON file: https://providers.openedx-lms.stepanok.com/p/northwind-education-group/directory.json (some of LMS in this JSON file are disabled)

@IvanStepanok
IvanStepanok marked this pull request as ready for review August 25, 2026 08:30
The wire format here already allowed it — api and oauth_client_id are nullable,
and Config falls back to the app's own client id. Nothing to change, but the
mobile working group settled that this is the model rather than an accident, so
it is worth a test that fails if someone tightens the DTO later.

The matching iOS change makes the same document decode there.
The file the apps read now says `format`, `include`, `name`, `description`,
`url` and `logo`, matching the schema being settled in the mobile working group
rather than the column names of the registry that happened to produce the first
one. A file written by hand and a file exported from a registry are now the same
shape, which was the point.

`id` becomes optional with it: a platform that names none is identified by its
address, which is unique within a directory anyway.

Also finishes the design parity pass. A platform with no logo drew one initial
on a tinted square here and two white initials on a filled one on iOS; both now
draw the filled badge, since that fallback only shows up for platforms that
never uploaded a logo — exactly the ones nobody looked at while comparing.
@mphilbrick211 mphilbrick211 moved this from Needs Triage to In Eng Review in Contributions Aug 26, 2026
@kdmccormick

Copy link
Copy Markdown
Member

Excited to see this move forward!

Could you add to your PR description to explain how AI was used and how you validated AI-generated code? https://github.com/openedx/.github/blob/master/AI_POLICY.md#pull-requests

The id came from the registry that produced the first document, where it is a
primary key. It means nothing to a client, so the schema is better without it.

What replaces it is the position in the file, not the URL. Two entries may
legitimately name the same address — the same LMS listed twice under different
branding — and identifying by URL merges them, so opening one row would give
another row's settings. Compose survived that by accident, because the list is
keyed by index; iOS did not, which is how it was found.

A test holds a two-entry document that shares one address, so neither platform
can regress into merging them.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core contributor PR author is a Core Contributor (who may or may not have write access to this repo). open-source-contribution PR author is not from Axim or 2U

Projects

Status: In Eng Review

Development

Successfully merging this pull request may close these issues.

5 participants